TIPS FOR REVIEW:
Compare the PR docs (v1.25.7 + latest commit on this PR): https://gyft.github.io/aws-lambda-powertools-python/latest/
Against the current: https://awslabs.github.io/aws-lambda-powertools-python/latest/
See Doc Fixes section for notes on specific fixes
Run make format-examples lint-examples to format and lint extracted examples

Issue #, if available:

• Docs: Move code snippets into dedicated python files add formatting and linting, fixing any outstanding errors #1064
• Papercuts priorization before we consider v2 #1009
• Docs: Event Handler - Broken AWS Serverless Application Model (SAM) example #1069

Description of changes:

Move code snippets into dedicated python files so they can be formatted (isort, black), and then embedded in the docs.

As part of the extraction a number of bugs was fixed, things like missing imports, python syntax errors, yaml formatting, invalid terraform and correct the line highlights.

A couple Makefile tasks where added to help verify changes (format-examplesmake task to runisortandblackon examples andlint-examplesmike task to runpython compileandcfn-linton examples).cfn-lint` may then become a dev dependency.

Directory Structure: Currently examples are moved under docs/examples and relates to the directory and file names of the *.md files: eg docs/core/logger.md examples are in docs/examples/core/logger/ folder.

Other things we can do: python syntax verification (black actually does a pretty good of checking for valid python) and cloudformation linting (cfn-lint) and sam validate.

Changes:

• Add format-examples make task to run isort and black on examples
• Add lint-examples make task to run python compile and cfn-lint on examples
• Converted docs/index.md examples
• Converted docs/core/event_handler/appsync.md examples
• Converted docs/core/event_handler/api_gateway.md examples
• Converted docs/core/logger.md examples
• Converted docs/core/metrics.md examples
• Converted docs/core/tracer.md examples
• Converted docs/tutorial/index.md examples
• Converted docs/utilities/batch.md examples
• Converted docs/utilities/data_classes.md examples
• Converted docs/utilities/feature_flags.md examples
• Converted docs/utilities/idempotency.md examples
• Converted docs/utilities/jmespath_functions.md examples
• Converted docs/utilities/middleware_factory.md examples
• Converted docs/utilities/parser.md examples
• Converted docs/utilities/parameters.md examples
• Converted docs/utilities/typing.md examples
• Converted docs/utilities/validation.md examples

Doc Fixes:

NOTE: During the extraction the following fixes was made, which could be fix earlier in a separate PR

• Change name for validator_function.py example to match up, see Validation - Validate function
• [ x] Fix ht_line invalid syntax in Validation - Validating custom formats - schema.py
• Fix template yml in indents Rest API - AWS Serverless Application Model (SAM) example example for Rest api (and fixes Docs: Event Handler - Broken AWS Serverless Application Model (SAM) example #1069)
• Fix json response example in Rest API - Fine grained response - Not formatted as json
• Fix Deserializing JSON before using as idempotency key example in JMESPath - Missing import
• Fix custom_jmespath_function.py example in JMESPath - Invalid python syntax
• Open links in new tabs for tracer page
• Fix metrics SAM template.yml indents
• Fix missing imports for Clear metrics tests
• Fix python syntax on Assert multiple EMF blobs with pytest example
• Fix example in FAQ section Cloning Logger config to all other registered standard loggers which results in a error AttributeError: module 'logging' has no attribute 'logger' on line 8
• Fix examples in Batch - Pydantic integration
• Clean up Batch - Accessing processed messages via context manager example removing unused imports and fix line highlights.
• Fix missing imports in Batch - Extending failure handling mechanism in BatchProcessor example
• Fix missing parameter in success_handler Batch - Creating a custom batch processor example
• Fix python syntax errors in Batch -Testing your code examples
• Fix import for Batch - Customizing boto configuration example
• Fix missing import for Parameters - Creating a S3 Provider to fetch parameters example
• Fix yaml indent in Idempotency -AWS Serverless Application Model (SAM) example
• Fix python syntax in Idempotency - Exception not affecting idempotency record sample example
• Fix python syntax in Idempotency - Reusing a DynamoDB table that uses a composite primary key example
• Fix python syntax in Idempotency - Using Idempotency with JSONSchema Validation utility example
• Fix sam template HomePage - Lambda Layer - SAM example
• Includes fix(docs): fix syntax errors in the lambda layer terraform example #1068 HomePage - Lambda Layer - Terraform example
• Fix sam template HomePage - SAR - SAM example
• Fix python syntax HomePage - SAR - CDK examples
• Fix template yml indents HomePage - Example: Least-privileged IAM permissions to deploy Layer example
• Fix missing imports for Parser - EventBridge Envelope example

Questions on the docs

During the conversion process some questions have some up for later review

• logger_two in this example for overriding log records will still include location as Logger can only be initialized once? A bug or confusing? (possible issue resolved by fix(logger-utils): ensure external loggers doesn't propagate logs on config copy #1075)

Other docs to extract

Only Doc string are remaining, which is also part of the generated api reference and may be resolved by #517

Checklist

• Meet tenets criteria
• Update tests
• Update docs
• PR title follows conventional commit semantics

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.